/*
 * Copyright (c) 2000 World Wide Web Consortium,
 * (Massachusetts Institute of Technology, Institut National de
 * Recherche en Informatique et en Automatique, Keio University). All
 * Rights Reserved. This program is distributed under the W3C's Software
 * Intellectual Property License. This program is distributed in the
 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 * PURPOSE.
 * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
 */
using System;

namespace org.w3c.dom
{

    /**
     * The <code>CharacterData</code> interface : Node with a set of 
     * attributes and methods for accessing character data in the DOM. For 
     * clarity this set is defined here rather than on each object that uses 
     * these attributes and methods. No DOM objects correspond directly to 
     * <code>CharacterData</code>, though <code>Text</code> and others do 
     * inherit the interface from it. All <code>offsets</code> in this interface 
     * start from <code>0</code>.
     * <p>As explained in the <code>DOMString</code> interface, text strings in 
     * the DOM are represented in UTF-16, i.e. as a sequence of 16-bit units. In 
     * the following, the term 16-bit units is used whenever necessary to 
     * indicate that indexing on CharacterData is done in 16-bit units.
     * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
     */
     public interface CharacterData : Node
    {
        /**
         * The character data of the node that implements this interface. The DOM 
         * implementation may not put arbitrary limits on the amount of data 
         * that may be stored in a <code>CharacterData</code> node. However, 
         * implementation limits may mean that the entirety of a node's data may 
         * not fit into a single <code>DOMString</code>. In such cases, the user 
         * may call <code>substringData</code> to retrieve the data in 
         * appropriately sized pieces.
         * @exception DOMException
         *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
         * @exception DOMException
         *   DOMSTRING_SIZE_ERR: Raised when it would return more characters than 
         *   fit in a <code>DOMString</code> variable on the implementation 
         *   platform.
         */
        String getData();//                            throws DOMException;
        void setData(String data);//                            throws DOMException;

        /**
         * The number of 16-bit units that are available through <code>data</code> 
         * and the <code>substringData</code> method below. This may have the 
         * value zero, i.e., <code>CharacterData</code> nodes may be empty.
         */
        int getLength();

        /**
         * Extracts a range of data from the node.
         * @param offsetStart offset of substring to extract.
         * @param countThe number of 16-bit units to extract.
         * @return The specified substring. If the sum of <code>offset</code> and 
         *   <code>count</code> exceeds the <code>length</code>, then all 16-bit 
         *   units to the end of the data are returned.
         * @exception DOMException
         *   INDEX_SIZE_ERR: Raised if the specified <code>offset</code> is 
         *   negative or greater than the number of 16-bit units in 
         *   <code>data</code>, or if the specified <code>count</code> is 
         *   negative.
         *   <br>DOMSTRING_SIZE_ERR: Raised if the specified range of text does 
         *   not fit into a <code>DOMString</code>.
         */
        String substringData(int offset,
                                    int count);//                                throws DOMException;

        /**
         * Append the string to the end of the character data of the node. Upon 
         * success, <code>data</code> provides access to the concatenation of 
         * <code>data</code> and the <code>DOMString</code> specified.
         * @param argThe <code>DOMString</code> to append.
         * @exception DOMException
         *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
         */
        void appendData(String arg);//                           throws DOMException;

        /**
         * Insert a string at the specified 16-bit unit offset.
         * @param offsetThe character offset at which to insert.
         * @param argThe <code>DOMString</code> to insert.
         * @exception DOMException
         *   INDEX_SIZE_ERR: Raised if the specified <code>offset</code> is 
         *   negative or greater than the number of 16-bit units in 
         *   <code>data</code>.
         *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
         */
        void insertData(int offset,
                               String arg);//                           throws DOMException;

        /**
         * Remove a range of 16-bit units from the node. Upon success, 
         * <code>data</code> and <code>length</code> reflect the change.
         * @param offsetThe offset from which to start removing.
         * @param countThe number of 16-bit units to delete. If the sum of 
         *   <code>offset</code> and <code>count</code> exceeds 
         *   <code>length</code> then all 16-bit units from <code>offset</code> 
         *   to the end of the data are deleted.
         * @exception DOMException
         *   INDEX_SIZE_ERR: Raised if the specified <code>offset</code> is 
         *   negative or greater than the number of 16-bit units in 
         *   <code>data</code>, or if the specified <code>count</code> is 
         *   negative.
         *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
         */
        void deleteData(int offset,
                               int count);//throws DOMException;

        /**
         * Replace the characters starting at the specified 16-bit unit offset 
         * with the specified string.
         * @param offsetThe offset from which to start replacing.
         * @param countThe number of 16-bit units to replace. If the sum of 
         *   <code>offset</code> and <code>count</code> exceeds 
         *   <code>length</code>, then all 16-bit units to the end of the data 
         *   are replaced; (i.e., the effect is the same as a <code>remove</code>
         *    method call with the same range, followed by an <code>append</code>
         *    method invocation).
         * @param argThe <code>DOMString</code> with which the range must be 
         *   replaced.
         * @exception DOMException
         *   INDEX_SIZE_ERR: Raised if the specified <code>offset</code> is 
         *   negative or greater than the number of 16-bit units in 
         *   <code>data</code>, or if the specified <code>count</code> is 
         *   negative.
         *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
         */
        void replaceData(int offset,
                                int count,
                                String arg);//throws DOMException;

    }
}